Greptile Summary

This PR adds two resilience features to the CDP connection layer: a keepalive mechanism that detects zombie WebSocket connections (by periodically sending Browser.getVersion and calling handleDeadConnection on timeout), and an exit strategy that calls process.exit when reconnection is exhausted or when no health check arrives within 5 minutes. Per-request timeouts are also introduced to prevent rawSend calls from hanging indefinitely.

Key changes:

• cdp.ts: Adds startKeepalive/stopKeepalive, handleDeadConnection, per-request timers on PendingRequest, stale-socket guard in attemptConnect, and renames reconnectOrCrash → reconnectWithRetries with disconnecting early-exit checks.
• health.ts: Adds a watchdog timer that exits the process if no /health ping is received for 5 minutes; response now includes cdpConnected status.
• timeouts.ts / limits.ts: New shared constants for reconnect delay, keepalive interval/timeout, request timeout, and reconnect retry count.
• browser.ts: Exposes isCdpConnected() delegating to cdp.isConnected().

Issues found:

• HEALTH_CHECK_TIMEOUT in health.ts is a local magic constant; per CLAUDE.md all timeout values must live in @browseros/shared/constants/timeouts. All other new timeouts in this PR were correctly placed there.
• The watchdog timer returned by createHealthRoute has no cleanup path. If a graceful shutdown takes longer than 5 minutes after health checks stop, the watchdog fires process.exit(GENERAL_ERROR) instead of allowing a clean exit.

Confidence Score: 4/5

• Safe to merge with minor follow-up; the keepalive and exit-strategy logic is correct and well-structured.
• The core reconnection and keepalive logic is sound: the stale-socket guard prevents double close handling, per-request timers prevent hung promises, and rejectPendingRequests properly clears all timers. The only concrete issues are a CLAUDE.md violation (magic constant HEALTH_CHECK_TIMEOUT should be in shared TIMEOUTS) and a missing watchdog cleanup on graceful shutdown — neither blocks correctness of the happy path.
• apps/server/src/api/routes/health.ts — watchdog timer has no cleanup mechanism and contains a magic constant that violates CLAUDE.md.

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant HC as Health Poller
    participant HR as HealthRoute (watchdog)
    participant B as Browser
    participant CDP as CdpBackend
    participant CR as Chromium

    Note over HR: watchdog starts on creation (5 min timer)

    loop every N seconds
        HC->>HR: GET /health
        HR->>HR: resetWatchdog()
        HR->>B: isCdpConnected()
        B->>CDP: isConnected()
        CDP-->>B: bool
        B-->>HR: bool
        HR-->>HC: {status:"ok", cdpConnected:bool}
    end

    Note over CDP: keepalive loop every 30s
    CDP->>CR: Browser.getVersion (10s race timeout)
    alt success
        CR-->>CDP: version response
        CDP->>CDP: clearTimeout(pendingTimer)
    else timeout / send failure
        CDP->>CDP: handleDeadConnection()
        CDP->>CDP: stopKeepalive()
        CDP->>CDP: ws.close() → ws=null
        CDP->>CDP: handleUnexpectedClose()
        CDP->>CDP: rejectPendingRequests()
        CDP->>CDP: reconnectWithRetries() [up to 3×, 5s delay each]
        alt reconnect succeeds
            CDP->>CR: connect WebSocket
            CR-->>CDP: open
            CDP->>CDP: startKeepalive()
        else all retries exhausted
            CDP->>CDP: process.exit(GENERAL_ERROR)
        end
    end

    alt no health check for 5 min
        HR->>HR: watchdog fires
        HR->>HR: process.exit(GENERAL_ERROR)
    end

_{Last reviewed commit: 193151d}